═══ 1. Introduction ═══ The REXX File Transfer Protocol (FTP) Application Program Interface (API) package provides access to the OS/2 TCP/IP FTP API's. It is assumed you are familiar with the basic FTP. The REXX FTP API function names are similar to the FTP subcommands. References For information on the FTP subcommands, refer to the IBM Transmission Control Protocol/Internet Protocol Version 2.0 for OS/2: User's Guide. For information on FTP API calls, refer to the IBM Transmission Control Protocol/Internet Protocol Version 2.0 for OS/2: Programmer's Reference. Requirements The REXX FTP API package requires the OS/2 TCP/IP product, version 2.0 or higher. The REXX feature from the OS/2 Setup and Installation window must be installed. To access the REXX feature, choose Selective Install from the OS/2 System Setup folder. Then from the System Configuration window, select OK to display the OS/2 Setup and Installation window. Check the REXX feature and select the Install push button. ═══ 2. Installation ═══ The REXX FTP API package is contained in the file rxftp.dll. This dynamic link library (DLL) needs to be placed in a directory listed in your LIBPATH statement in your CONFIG.SYS file. To get access to the functions in the REXX FTP API package, execute the following REXX code: rc = RxFuncAdd("FTPLoadFuncs","rxFtp","FTPLoadFuncs") rc = FtpLoadFuncs() To unload the DLL, you should first call the FtpDropFuncs() function, then exit all CMD.EXE shells. After exiting all the command shells, the DLL will be dropped by OS/2 and can be deleted or replaced. ═══ 3. Return Values ═══ Select an item: Set errors FtpSetUser() FtpSetBinary() FTP errors All other functions ═══ Set Error Codes ═══ The FtpSetUser() and FtpSetBinary() functions return the Set error codes: 1 is the return code if the string passed is valid. 0 is the return code if the string is not valid. ═══ FTP Error Codes ═══ All of the REXX FTP API functions, except FtpSetUser() and FtpSetBinary(), return the FTP error codes: The FTP error codes will have one of the following values: "0" for a successful call "-1" if there is an error during FTP function call If the function returns a "-1" for an error code, the variable FTPERRNO will be set to one of the following values (or a numeric value if the number is not one of these values): "FTPSERVICE" unknown service "FTPHOST" unknown host "FTPSOCKET" unable to obtain socket "FTPCONNECT" unable to connect to server "FTPLOGIN" login failed "FTPABORT" transfer stopped "FTPLOCALFILE" problem opening local file "FTPDATACONN" problem initializing data connection "FTPCOMMAND" command failed "FTPPROXYTHIRD" proxy server does not support third party transfers "FTPNOPRIMARY" no primary connection for proxy transfer ═══ 4. Functions ═══ Most of the REXX FTP API functions correspond to their like-named FTP subcommands. Opening and Closing Functions FtpLoadFuncs() FtpDropFuncs() FtpVersion() FtpSetUser() FtpSetBinary() FtpLogoff() File Action Functions FtpAppend() FtpDelete() FtpRename() FtpGet() FtpPut() FtpPutUnique() Directory Listing Functions FtpLs() FtpDir() Directory Action Functions FtpChDir() FtpMkDir() FtpRmDir() FtpPwd() Remote Server Functions FtpQuote() FtpSite() FtpSys() FtpProxy() FtpPing() ═══ Open/Close ═══  FtpLoadFuncs()  FtpDropFuncs()  FtpVersion()  FtpSetUser()  FtpSetBinary()  FtpLogoff()  Calls by Task ═══ File Actions ═══  FtpGet()  FtpPut()  FtpPutUnique()  FtpAppend()  FtpDelete()  FtpRename()  Calls by Task ═══ Directory List ═══  FtpLs()  FtpDir()  Calls by Task ═══ Directory Actions ═══  FtpChDir()  FtpMkDir()  FtpRmDir()  FtpPwd()  Calls by Task ═══ Remote Servers ═══  FtpQuote()  FtpSite()  FtpSys()  FtpProxy()  FtpPing()  Calls by Task ═══ 4.1. FtpAppend() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpAppend() ═══ /* Copies a file from the local host to a remote host and adds the local file to the end of the file on the remote host */ rc = FtpAppend(localFile,remoteFile<,"Binary"|"Ascii">) ═══ Definition for FtpAppend() ═══ The FtpAppend() call copies a local file to a remote host and adds the local file to the end of the file on the remote host. As an option, you can specify the transfer to occur in binary mode or text (ASCII) mode. If a you do not specify the transfer mode with this call, the mode specified with the FtpSetBinary() call is used. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpAppend() ═══ localFile name of the file to be copied from the local host. remoteFile name of the file on the remote host to which the local file is added to. "Binary" sets the file transfer mode to binary or image. "Ascii" sets the file transfer type to ASCII (flat text). ═══ Return Values for FtpAppend() ═══ FTP error codes ═══ 4.2. FtpChDir() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpChDir() ═══ /* Changes the working directory on the remote host */ rc = FtpChDir(directory) ═══ Definition for FtpChDir() ═══ The FtpChDir() call changes the working directory on the remote host. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpChDir() ═══ directory change to this directory name on the remote host. ═══ Return Values for FtpChDir() ═══ FTP error codes ═══ 4.3. FtpDelete() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpDelete() ═══ /* Deletes a single file on the remote host */ rc = FtpDelete(remoteFile) ═══ Definition for FtpDelete() ═══ The FtpDelete() call deletes a single file on a remote host. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpDelete() ═══ remoteFile name of the file on the remote host which will be deleted. ═══ Return Values for FtpDelete() ═══ FTP error codes ═══ 4.4. FtpDir() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpDir() ═══ /* Gets the directory information for the current directory of the remote host */ rc = FtpDir(pattern,stem) ═══ Definition for FtpDir() ═══ The FtpDir() call gets the directory information for the current directory of the remote host. The FtpDir() call gets the directory information in long format. The directory information is placed into the stemmed variables. The remote host is specified with the FtpSetUser() call. The FtpDir() call is similar to the FtpLs() call, except that the FtpLs() call gets the directory information in short format. ═══ Parameters for FtpDir() ═══ pattern file name or pattern of the files to be listed on the remote host. Patterns are any combination of ASCII characters. The following two characters have special meanings: * shows that any character or group of characters can occupy that position in the pattern. ? shows that any single character can occupy that position in the pattern. stem specifies the variable stem. The stem string should end with a period ("."). When the function completes, the variable stem || "0" will be set to the number of stem variables returned. The directory information is set in variables stem || "1", stem || "2", etc. The "." is not appended, so you should specify it in the stem name passed to the function. For example, the following call: rc=FtpDir("ftpx*.c","files.") located 3 files in the current directory of the remote host. The stemmed variables are: Variable Value files.0 3 files.1 ftpxdir.c files.2 ftpxren.c files.3 ftpxdel.c ═══ Return Values for FtpDir() ═══ FTP error codes ═══ 4.5. FtpDropFuncs() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpDropFuncs() ═══ /* Drops all functions in the REXX FTP API package */ rc = FtpDropFuncs() ═══ Definition for FtpDropFuncs() ═══ The FtpDropFuncs() call drops all the functions in the REXX FTP API package. ═══ Parameters for FtpDropFuncs() ═══ none ═══ Return Values for FtpDropFuncs() ═══ FTP error codes ═══ 4.6. FtpGet() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpGet() ═══ /* Copies a single file from a remote host to your workstation */ rc = FtpGet(localFile,remoteFile<,"Binary"|"Ascii">) ═══ Definition for FtpGet() ═══ The FtpGet() call copies a single file from the remote host to the local workstation. The remote file name does not have to be the same as the local file name. As an option, you can specify the transfer to occur in binary mode or text (ASCII) mode. If a you do not specify the transfer mode with this call, the mode specified with the FtpSetBinary() call is used. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpGet() ═══ localFile name of the file on the local host that was copied from the remote host. remoteFile name of the file on the remote host that was copied to the local workstation. "Binary" sets the file transfer mode to binary or image. "Ascii" sets the file transfer type to ASCII (flat text). ═══ Return Values for FtpGet() ═══ FTP error codes ═══ 4.7. FtpLoadFuncs() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpLoadFuncs() ═══ /* Loads all functions in the REXX FTP API package */ rc = FtpLoadFuncs() ═══ Definition for FtpLoadFuncs() ═══ The FtpLoadFuncs() call loads all the functions in the REXX FTP API package. ═══ Parameters for FtpLoadFuncs() ═══ FtpLoadFuncs() - If any parameters are passed to this function, it will bypass the copyright information that is normally displayed. All parameters are ignored (except to determine whether or not to bypass displaying the information). ═══ Return Values for FtpLoadFuncs() ═══ FTP error codes ═══ 4.8. FtpLogoff() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpLogoff() ═══ /* Ends all FTP sessions with the remote host */ rc = FtpLogoff() ═══ Definition for FtpLogoff() ═══ The FtpLogoff() call ends all FTP sessions with the remote host. The host, user ID, password, and account will be reset after the FtpLogoff() call. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpLogoff() ═══ none ═══ Return Values for FtpLogoff() ═══ FTP error codes ═══ 4.9. FtpLs() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpLs() ═══ /* Gets the directory information for the current directory of the remote host */ rc = FtpLs(pattern,stem) ═══ Definition for FtpLs() ═══ The FtpLs() call gets the directory information for the current directory of the remote host. The FtpLs() call gets the directory information in short format. The directory information is placed into the stemmed variables. The remote host is specified with the FtpSetUser() call. The FtpLs() call is similar to the FtpDir() call, except that the FtpDir() call gets the directory information in long format. ═══ Parameters for FtpLs() ═══ pattern file name or pattern of the files to be listed on the remote host. Patterns are any combination of ASCII characters. The following two characters have special meanings: * shows that any character or group of characters can occupy that position in the pattern. ? shows that any single character can occupy that position in the pattern. stem specifies the variable stem. The stem string should end with a period ("."). When the function completes, the variable stem || "0" will be set to the number of stem variables returned. The directory information is set in variables stem || "1", stem || "2", etc. The "." is not appended, so you should specify it in the stem name passed to the function. For example, the following call: rc=FtpLs("ftpx*.c","files.") located 3 files in the current directory of the remote host. The stemmed variables are: Variable Value files.0 3 files.1 ftpxdir.c files.2 ftpxren.c files.3 ftpxdel.c ═══ Return Values for FtpLs() ═══ FTP error codes ═══ 4.10. FtpMkDir() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpMkDir() ═══ /* Makes a new directory on the remote host */ rc = FtpMkDir(directory) ═══ Definition for FtpMkDir() ═══ The FtpMkDir() call makes a new directory on the remote host. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpMkDir() ═══ directory make this directory name on the remote host. ═══ Return Values for FtpMkDir() ═══ FTP error codes ═══ 4.11. FtpPing() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpPing() ═══ /* Sends a ping to a remote host */ rc = FtpPing(host,length) ═══ Definition for FtpPing() ═══ The FtpPing() call sends a ping to the remote host. The FtpPing() call tries to resolve the host name through a name server. If a name server is not present, FtpPing() call searches the TCPIP\ETC\HOSTS file for a matching host name. ═══ Parameters for FtpPing() ═══ host identifies the name for the remote host. length identifies the length of the ping packets. ═══ Return Values for FtpPing() ═══ If no error occurred, FtpPing() call returns the number of milliseconds it took for the echo to return. If an error occurred, refer to the FTP error codes. ═══ 4.12. FtpProxy() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpProxy() ═══ /* Copies a file between two remote servers */ rc = FtpProxy(host1,userid1,password1,account1, host2,userid2,password2,account2, file1,file2<,"Binary"|"Ascii">) ═══ Definition for FtpProxy() ═══ The FtpProxy() call copies a file from one remote host to another remote host. You can use different file names on each host. The "target" host, user ID, password, and account are listed before the "copy from" host, user ID, password, and account. The transfer mode, Binary or ASCII, is optional. ═══ Parameters for FtpProxy() ═══ host1 identifies the "target" remote host. userid1 identifies the user on the "target" remote host. password1 supplies the password on the "target" remote host. account1 supplies host-dependent account information on the "target" remote host. Use "NULL" if there is no account value. host2 identifies the "copy from" remote host. userid2 identifies the user on the "copy from" remote host. password2 supplies the password on the "copy from" remote host. account2 supplies host-dependent account information on the "copy from" remote host. Use "NULL" if there is no account value. file1 identifies the files name on the "target" remote host. file2 identifies the files name on the "copy from" remote host. "Binary" sets the file transfer mode to binary or image. "Ascii" sets the file transfer type to ASCII (flat text). ═══ Return Values for FtpProxy() ═══ "0 " for a successful call "-1" if there is an error during the FtpProxy() call FTP error codes ═══ 4.13. FtpPut() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpPut() ═══ /* Copies a single file from your workstation to a remote host */ rc = FtpPut(localFile,remoteFile<,"Binary"|"Ascii">) ═══ Definition for FtpPut() ═══ The FtpPut() call copies a single file from your workstation to a remote host. The local file name does not have to be the same as the remote file name. As an option, you can specify the transfer to occur in binary mode or text (ASCII) mode. If a you do not specify the transfer mode with this call, the mode specified with the FtpSetBinary() call is used. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpPut() ═══ localFile name of the file on the local host that was copied to the remote host. remoteFile name of the file on the remote host that was copied from the local workstation. "Binary" sets the file transfer mode to binary or image. "Ascii" sets the file transfer type to ASCII (flat text). ═══ Return Values for FtpPut() ═══ FTP error codes ═══ 4.14. FtpPutUnique() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpPutUnique() ═══ /* Copies a single file from your workstation to a remote host. Ensures the file name is unique on the remote host. */ rc = FtpPutUnique(localFile,remoteFile<,"Binary"|"Ascii">) ═══ Definition for FtpPutUnique() ═══ The FtpPutUnique() call copies a single file from your workstation to a remote host. The file name on the remote host must be unique. Therefore, files on the remote host are not overwritten by files from your workstation. The local file name does not have to be the same as the remote file name. As an option, you can specify the transfer to occur in binary mode or text (ASCII) mode. If a you do not specify the transfer mode with this call, the mode specified with the FtpSetBinary() call is used. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpPutUnique() ═══ localFile name of the file on the local host that was copied to the remote host. remoteFile name of the file on the remote host that was copied from the local workstation. "Binary" sets the file transfer mode to binary or image. "Ascii" sets the file transfer type to ASCII (flat text). ═══ Return Values for FtpPutUnique() ═══ FTP error codes ═══ 4.15. FtpPwd() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpPwd() ═══ /* Gets the current directory for the remote host */ rc = FtpPwd(dirName) ═══ Definition for FtpPwd() ═══ The FtpPwd() call (print working directory) gets the name of the current working directory of the remote host and places the current working directory in the variable "dirName". The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpPwd() ═══ dirName returns the current working directory of the remote host. ═══ Return Values for FtpPwd() ═══ FTP error codes ═══ 4.16. FtpQuote() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpQuote() ═══ /* Sends a string to a remote server */ rc = FtpQuote(quote) ═══ Definition for FtpQuote() ═══ The FtpQuote() call sends the specified string verbatim to the remote host. Your server must support the FTP commands sent by the FtpQuote() call. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpQuote() ═══ quote the string that is sent verbatim to the remote server. ═══ Return Values for FtpQuote() ═══ FTP error codes ═══ 4.17. FtpRename() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpRename() ═══ /* Renames a single file on the remote host */ rc = FtpRename(oldFile,newFile) ═══ Definition for FtpRename() ═══ The FtpRename() call changes the name of a file on the remote host. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpRename() ═══ oldFile original name of the file on the remote host. newFile new name of the file on the remote host. ═══ Return Values for FtpRename() ═══ FTP error codes ═══ 4.18. FtpRmDir() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpRmDir() ═══ /* Removes a directory on the remote host */ rc = FtpRmDir(directory) ═══ Definition for FtpRmDir() ═══ The FtpRmDir() call removes a directory on the remote host. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpRmDir() ═══ directory removes this directory name on the remote host. ═══ Return Values for FtpRmDir() ═══ FTP error codes ═══ 4.19. FtpSetBinary() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpSetBinary() ═══ /* Identifies the default text translation mode as binary or ASCII */ rc = FtpSetBinary("Binary"|"Ascii") ═══ Definition for FtpSetBinary() ═══ The FtpSetBinary() call sets the default text translation mode to binary or ASCII for functions that can use this. You can override this Binary or Ascii setting by any function that takes "Binary"|"Ascii" as an optional parameter. The FtpSetBinary() call can be passed as an abbreviation. For "BINARY", you can use "b" or "BIN". For "ASCII", you can use "as". ═══ Parameters for FtpSetBinary() ═══ "Binary" sets the file transfer mode to binary or image. "Ascii" sets the file transfer type to ASCII (flat text). ═══ Return Values for FtpSetBinary() ═══ Set error codes ═══ 4.20. FtpSetUser() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpSetUser() ═══ /* Identifies the host, user ID, password, and account for the remote host */ rc = FtpSetUser(host,userid,password<,account>) ═══ Definition for FtpSetUser() ═══ The FtpSetUser() call sets the host, user ID, and password for the remote host. Most other REXX FTP API calls require a host, user ID, and password to be set. Optionally, the FtpSetUser() call sets the user's account. The host, userid, password, and account are retained during the life of the process. If you are using the REXX FTP API package within a .CMD file run the OS/2 prompt, this means the life of the CMD.EXE process. You may want to 'blank' out the password (at least) when you are finished, to prevent unauthorized access to a host you previously used. The FtpLogoff() function also resets these values. ═══ Parameters for FtpSetUser() ═══ host name of the remote host to which you want to connect. userid identifies you to the FTP server. password supplies a password to the remote host. account supplies host-dependent account information. ═══ Return Values for FtpSetUser() ═══ Set error codes ═══ 4.21. FtpSite() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpSite() ═══ /* Sends site information to the remote host */ rc = FtpSite(site) ═══ Definition for FtpSite() ═══ The FtpSite() call sends information to the remote host. Your server must support the FTP information sent by the FtpSite() call. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpSite() ═══ site the string that is sent to the remote host to provide services specific to the remote host. ═══ Return Values for FtpSite() ═══ FTP error codes ═══ 4.22. FtpSys() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpSys() ═══ /* Returns the name of the operating system that the server is running */ rc = FtpSys(operSys) ═══ Definition for FtpSys() ═══ The FtpSys() call returns the FTP server description of the operating system running on the remote host. The remote host is specified with the FtpSetUser() call. ═══ Parameters for FtpSite() ═══ operSys the FTP server description of the operating system running on the remote host. ═══ Return Values for FtpSys() ═══ FTP error codes ═══ 4.23. FtpVersion() ═══ Select an item:  Syntax  Parameters  Return Values  Definition  Related Calls ═══ Syntax for FtpVersion() ═══ /* Identifies the version of the REXX FTP API package */ rc = FtpVersion(variable) ═══ Definition for FtpVersion() ═══ The FtpVersion() call identifies the version of the REXX FTP API package. The current version is 2.0. ═══ Parameters for FtpVersion() ═══ variable returns the version of REXX FTP API program that you are running. ═══ Return Values for FtpVersion() ═══ The version number is returned in the variable that you pass in the function. The actual return code can be ignored.